Alqor — Bölmə 13: Alət Zənciri#

13.1 Quraşdırma#

Hər quraşdırıcıda Python daxildir — sistemdə əlavə heç nə tələb olunmur. Bütün fayllar: https://github.com/vugarfamiloglu/alqor/releases.

Quraşdırılan əmrlər:

alqor           # əsas CLI (işlət, yeni, qur, sına, yerləşdir, …)
alqorpm         # paket meneceri (§ 8.9)
alqorlint       # linter (§ 13.4)
alqorfmt        # formatter (§ 13.3)
alqorls         # LSP serveri (§ 13.8)
alqor-studio    # Alqor Studio IDE (Linux/macOS; Windows-da Başlat menyusu)
~/.alq/         # istifadəçi ayarları və paket keşi

Quraşdırıcıları Alqor özü qurur: alqor qur --alqor --platforma windows|linux|macos [--arx x86_64|aarch64] (§ 13.2).

13.2 alqor — əsas CLI#

alqor yeni <ad>                  # yeni layihə yarat
alqor yeni <ad> --şablon veb     # şablonla (konsol | veb | desktop | kitabxana)
alqor işlət <fayl>               # kompilyasiyasız işlət (VM)
alqor işlət                      # layihənin giriş nöqtəsini işlət
alqor qur                        # kompilyasiya et
alqor sına                       # testləri işlət
alqor təmizlə                    # qurma nəticələrini sil
alqor yoxla                      # kompilyasiya etmədən yoxla (sürətli)
alqor format                     # kodu formatla
alqor sənəd                      # sənəd yarat
alqor söhbət                     # REPL başlat
alqor paketlə                    # quraşdırıcı yarat
alqor yerləşdir                  # yerləşdir
alqor versiya
alqor kömək <əmr>

Etalon implementasiyada vəziyyət#

Python etalonunda CLI python alqorc.py <əmr> kimi çağırılır. Hər əmrin ASCII ləqəbi var (işlət = islet = run) — Windows konsolunda Azərbaycan hərfləri yazmaq çətin olanda.

Repo kökündəki alqor.cmd (Windows) və alqor (Linux/macOS) bu əmrləri alqor yeni … kimi çağırmağa imkan verir.

qur etalon implementasiyada. Maşın koduna kompilyator hələ yoxdur. alqor qur Python zipapp yaradır: qurma/<ad>.pyz faylının içində icra mühiti və layihənin faylları (mənbə, şablon, statik) var; sınaq/, sənəd/, qurma/ daxil edilmir. İlk işə salınmada layihə faylları keş qovluğuna açılır (ALQOR_KES ilə dəyişdirilir). python ad.pyz (Windows) və ya ./ad.pyz (Linux/macOS) ilə işləyir. --tip — paketdən əvvəl tip yoxlaması. Aşağıdakı --hədəf seçimləri yerli kompilyatorla gələcək.

alqor qur --exe [fayl.alq] [--konsol|--pəncərə] — tək Windows .exe faylı (qurma/<ad>.exe); Alqor və Python quraşdırılmamış kompüterdə də işləyir. Quruluş: Rust başladıcısı (alqor-rs/baslatici/)

• sıxılmış yük (Python + .pyz) + izləyici (ALQORPAK). İlk işə

salınmada yük %LOCALAPPDATA%\Alqor\tetbiqler\<ad>-<id>\-yə açılır. gətir pəncərə/gətir vidjet olan proqram konsolsuz qurulur.

Quraşdırıcılar — alqor qur --quraşdırıcı (--platforma linux,windows,macos, --python-daxil). Xarici alət tələb olunmur:

--python-daxil Windows paketinə Python-un rəsmi embeddable paylamasını qoyur (bir dəfə endirilir). Manifestdə [quraşdırıcı]: başlıq, naşir, ikon, konsol = yanlış (pəncərəli tətbiq), uzantılar = [".kitab"].

alqor qur --studio [qovluq] — Alqor Studio-nun özünün quraşdırıcıları: .alq faylları Studio ilə açılır (alqor studio fayl.alq faylı açıb başlayır), menyuda və masaüstündə "Alqor Studio" ikonu. | yerləşdir [fayl] [--statik\|--server] [--çıxış q] | ✅ vebə yerləşdirmə paketi — aşağıya baxın | | paketlə | planlaşdırılır (qur --quraşdırıcı onu əvəz edir) |

alqor yerləşdir — proqramı internetə çıxarmaq üçün hazır qovluq (standart: qurma/yerləşdir/). Növ layihəyə baxıb seçilir:

Hər iki halda YERLESDIR.md platformalar üzrə addımları verir. Sintaksis xətası olan proqram yerləşdirilmir (çıxış kodu 2). JS-də olmayan modul işlədən proqram üçün --statik aydın xəta verir və --server-i təklif edir. Server paketində port PORT mühit dəyişənindən gəlir (§ 11, dinlə), Dockerfile ALQOR_HOST=0.0.0.0 qoyur. --çıxış docs GitHub Pages-in /docs rejimi üçündür.

alqor qur seçimləri#

alqor qur --hədəf linux-x64      # linux-x64 | linux-arm64 | veb | wasm
                                 # windows-x64 | macos-arm64
alqor qur --buraxılış            # optimallaşdırılmış
alqor qur --debaq                # debaq simvolları ilə
alqor qur --optimallaşdırma 3    # 0..3
alqor qur --statik               # asılılıqsız binar
alqor qur --kiçik                # minimum ölçü
alqor qur --çıxış ./bin/proqram
alqor qur --izlə                 # fayl dəyişəndə avtomatik yenidən qur

alqor işlət seçimləri#

alqor işlət --izlə               # dəyişiklikdə yenidən işlət
alqor işlət --profil             # performans profili
alqor işlət --iddia-saxla
alqor işlət -- arq1 arq2         # proqrama arqument ötür

13.3 alqorfmt — formatter#

alqorfmt .                       # bütün faylları formatla
alqorfmt --yoxla .               # dəyişiklik lazımdırmı (CI üçün)
alqorfmt --fərq .                # fərqi göstər
alqorfmt --ascii-düzəlt .        # ASCII açar sözləri kanonik formaya çevir
alqorfmt --homoqlif-düzəlt .     # gizli simvolları düzəlt

Standart qaydalar#

Təhlükəsizlik zəmanəti#

Formatlayıcı proqramın mənasını dəyişə bilməz. Format edilmiş mətn yenidən leksə və ayrılır; token axını (ASCII açar sözlərin kanonik forması istisna), JSX məzmunu və sintaksis ağacı (mövqelər nəzərə alınmadan) orijinalla eyni olmalıdır. Fərq çıxarsa fayl toxunulmaz qalır və xəta bildirilir. Sintaksis xətası olan fayl format edilmir.

Girinti alqoritmi#

Girinti açar söz sayğacından deyil, parserdən gəlir: parser hər tokenin neçə blok gövdəsinin içində olduğunu qeyd edir. Mötərizə içindəki çoxsətirli bloklar (arqument kimi verilən funksiya, siyahıdakı əgər … yoxsa … son) eyni mötərizədəki qonşu sətrə nisbətən girintilənir. Davam sətirlərinin əl ilə hizalanması qorunur, amma açan sətirdən ən azı bir pillə dərin olmalıdır.

Çoxsətirli mətn ("""…""", x"""…""") və JSX daxili yalnız bütöv sürüşdürülür — dəyəri dəyişmir. Sətir sonu şərhlərinin hizalanması qorunur; yalnız şərhdən ibarət sətir növbəti kod sətrinin girintisini alır.

Etalon implementasiyada vəziyyət#

Çıxış kodları: 0 — uğurlu / format lazım deyil, 1 — --yoxla rejimində format lazımdır, 2 — format edilə bilməyən fayl var (sintaksis xətası), 3 — yanlış istifadə.

Alqor Studio-da Ctrl+Shift+F eyni formatlayıcını çağırır.

Konfiqurasiya — layihe.alq:

[format]
girinti = 4
maks_sətir = 100
sondakı_vergül = doğru
ascii_düzəlt = doğru

13.4 alqorlint — linter ✅#

alqor lint .                     # və ya ./alqorlint .
alqor lint --düzəlt .            # avtomatik düzəldiləni düzəlt
alqor lint --sərtlik sərt .      # sərbəst | normal | sərt
alqor lint --json .              # CI və redaktorlar üçün
alqor lint --qaydalar            # bütün qaydalar

Lint nəticələri alqorls vasitəsilə VS Code-da və Alqor Studio-nun «Problemlər» panelində də görünür; düzəldilə bilənlər üçün sürətli düzəliş (quick fix) təklif olunur.

Qaydalar#

ALQ-Y001 və ALQ-Y014 tip yoxlayıcısının ALQ-T024 / ALQ-T026 tapıntılarıdır — lint hesabatında qayda adı ilə göstərilir.

Konfiqurasiya#

[lint]
sərtlik = "normal"        # sərbəst: yalnız potensial xəta və təhlükəsizlik
                          # sərt: məlumat səviyyəli qaydalar da xəbərdarlıq olur
söndür = ["uzun-sətir"]   # ad, kod və ya "kateqoriya-*" / "adlandırma-*"
xəta = ["gizli-açar"]     # xəbərdarlığı xətaya qaldır
maks_funksiya_sətri = 50
maks_dərinlik = 4
maks_sətir = 100
maks_parametr = 6

Söndürmə şərhləri:

dəyişən parol = "test123"     // lint: söndür gizli-açar
// alqor: lint-söndür adlandırma-*        (bütün fayl üçün)

Çıxış kodu: xəta varsa 1 (--xəbərdarlıq-xətadır ilə xəbərdarlıqda da).

13.5 alqortest — test işlədici#

alqortest                        # bütün testlər
alqortest sınaq/auth_sınaq.alq # bir fayl
alqortest --filtr "istifadəçi"   # ada görə
alqortest --örtük                # kod örtüyü hesabatı
alqortest --izlə                 # dəyişiklikdə yenidən işlət
alqortest --paralel 4
alqortest --təkrar 100           # flaky test axtarışı

Çıxış:

  Alqor Test 1.0.0

  sınaq/riyazi_sınaq.alq
    ✓ toplama düzgündür                        0.3ms
    ✓ bölmə sıfıra xəta atır                   0.1ms
    ✗ kvadrat kök mənfi ədəddə                 0.2ms

      Gözlənilən: ƏdədDeyil
      Alınan:     0.0
      sınaq/riyazi_sınaq.alq:24:5

  sınaq/mətn_sınaq.alq
    ✓ böyük hərf azərbaycan qaydası ilə         0.1ms
    ✓ "ışıq".böyüyə() == "IŞIQ"                 0.1ms

  Nəticə: 4 uğurlu, 1 uğursuz, 0 atlanmış      1.2s
  Örtük:  87.3% (1243/1424 sətir)

Etalon implementasiyada vəziyyət#

alqor sına (və ya alqortest): yol verilməsə layihənin sınaq/ qovluğu; qovluqda sınaq/, sinaq/, test/ altındakı və adı _sınaq.alq ilə bitən fayllar. Hər fayl ayrı interpretatorda işləyir.

13.6 alqordoc — sənəd generatoru#

alqordoc                         # HTML sənəd yarat
alqordoc --format markdown
alqordoc --çıxış sənəd/
alqordoc --server                # canlı önizləmə ilə

Mənbə:

/// Verilən radiusla dairənin sahəsini hesablayır.
///
/// # Parametrlər
/// - `radius`: Dairənin radiusu (müsbət olmalıdır)
///
/// # Qaytarır
/// Dairənin sahəsi
///
/// # Xətalar
/// `radius` mənfidirsə `ArqumentXətası` atır
///
/// # Nümunə
/// ```alqor
/// yaz(dairəSahəsi(5))    // 78.539...
/// ```
ixrac et funksiya dairəSahəsi(radius: onluq) -> onluq
    təmin radius >= 0 yoxsa
        at ArqumentXətası("Radius mənfi ola bilməz")
    son
    qaytar riyaziyyat.Pİ * radius ** 2
son

Sənəddəki nümunə kodlar test kimi də işlədilir (alqor sına --sənəd): hər ```alqor bloku faylın adları əlçatan olan ayrıca proqram kimi icra olunur.

Qaydalar. /// sənədi elanın üstündə yazılır və ixrac et, görünüş sözləri, annotasiyalar (@sınaq) aradan keçir. //! faylın sənədidir. Faylda ixrac et varsa yalnız ixrac olunanlar, yoxdursa gizli olmayan bütün yuxarı səviyyəli elanlar sənədləşdirilir; sinif üzvləri də daxildir. İmza mənbədən olduğu kimi götürülür. Sənəd mətnində Markdown alt çoxluğu: başlıq (#), siyahı, kod, qalın, kod bloku.

13.7 alqor söhbət — REPL#

$ alqor söhbət
Alqor 1.0.0 — interaktiv rejim
Azərbaycan dilində proqramlaşdırma dili

  :kömək   bütün əmrlər
  :çıx     çıxış (Ctrl+D də işləyir)

alqor> 2 + 2
4  // tam

alqor> "ışıq".böyüyə()
"IŞIQ"  // mətn

alqor> funksiya ikiqat(x: tam) -> tam
  ...     qaytar x * 2
  ... son
  funksiya `ikiqat` təyin edildi

alqor> ikiqat(21)
42  // tam

alqor> nəticə + 1
43  // tam

Davranış#

Meta-əmrlər#

Hər meta-əmrin ASCII ləqəbi də var: :komek, :cix, :siyahi, :temizle, :yukle, :tarixce, :herfler, :elifba.

Üzv adlarında ASCII təklifi#

ASCII çevrilməsi yalnız açar sözlərə aiddir. Üzv adında ASCII yazılsa, REPL düzgün adı təklif edir:

alqor> [1, 2, 3].cem()
✖ ALQ-T006  `siyahı[tam]` tipində `cem` üzvü yoxdur — `cəm` demək
            istəyirdiniz? ASCII çevrilməsi yalnız AÇAR SÖZLƏRƏ aiddir,
            üzv adlarına yox

13.8 alqorls — LSP serveri#

alqor ls --stdio         # redaktor özü işə salır (JSON-RPC, stdin/stdout)

Asılılıqsız, LSP 3.17 alt çoxluğu (alqorc/alqor/alqorls.py). Analiz alqor yoxla ilə eynidir: mənbə → lekser → parser → tip yoxlayıcısı. Tip yoxlayıcısı qeyd rejimində işləyir — hər ad istifadəsinin hansı elana bağlandığını və hər a.b ifadəsinin tipini yadda saxlayır.

Fayl idxalı tip yoxlayıcısında da görünür: gətir "./x.alq" kimi m faylı ayrıca ayrılıb yoxlanır (keşlənir, dövri idxal qorunur), onun qlobal elanları m-in üzvləri olur — m.yoxdur → ALQ-M002, tapılmayan fayl → ALQ-M001.

Redaktorlar:

TextMate qrammatikası və language-configuration.json açar söz siyahısından yaradılır (python -m alqor.qrammatika --yaz); sınaq onların köhnəlmədiyini yoxlayır.

---|---| | Sintaksis vurğulama | ✓ | | Avtotamamlama | ✓ (kontekstli, sənədlə) | | Təyinata get | ✓ | | İstinadları tap | ✓ | | Ad dəyişdirmə | ✓ (bütün layihədə) | | Hover sənədi | ✓ (Azərbaycan dilində) | | Diaqnostika | ✓ (yazarkən) | | Sürətli düzəlişlər | ✓ (ə çatışmır, idxal əlavə et...) | | Kod formatlaması | ✓ | | Kod linzaları | ✓ (istinad sayı, test işlət) | | Sənəd sxemi | ✓ | | Semantik rənglər | ✓ | | Debaq (DAP) | ✓ | | Azərbaycan klaviatura köməyi | ✓ (xüsusi genişləndirmə) |

13.9 Alqor Studio — IDE#

┌─────────────────────────────────────────────────────────────────┐
│ Fayl Redaktə Seçim Görünüş Keç İşlət Debaq Alətlər Kömək  [⌕]   │
├──────────────┬─────────────────────────┬────────────────────────┤
│ 📁 LAYİHƏ    │  əsas.alq        ×    │  CANLI ÖNİZLƏMƏ        │
│              │                         │  ┌──────────────────┐  │
│ ▼ mənbə/     │ 1  gətir veb            │  │                  │  │
│   əsas.alq │ 2                       │  │  Salam, dünya!   │  │
│   model.alq  │ 3  funksiya əsas()      │  │                  │  │
│ ▼ sınaq/     │ 4      dəyişən s =      │  │  [Bas mənə]      │  │
│   test.alq │ 5          yeni Server()│  │                  │  │
│ ▶ statik/    │ 6      s.dinlə(8080)    │  └──────────────────┘  │
│   layihe.alq │ 7  son                  │  🔄 Avtomatik yenilənir │
│              │                         │                        │
│              │ ⌨ ə ı ğ ş ç ö ü İ       ├────────────────────────┤
│              │ AZ klaviatura: AÇIQ     │  TERMİNAL              │
│              │                         │  $ alqor işlət         │
├──────────────┴─────────────────────────┤  Server: :8080         │
│ ⚠ PROBLEMLƏR (1)                       │  ✓ Kompilyasiya 0.3s   │
│ ALQ-T024 sətir 4: `s` istifadə olunmur │                        │
└────────────────────────────────────────┴────────────────────────┘

Əsas xüsusiyyətlər#

Texnologiya: Tauri + CodeMirror 6. Ölçü: ~15 MB (Electron ekvivalenti ~150 MB).

13.10 Debaq#

Hazırda debaq alqor dap (§ 13.8) üzərindədir: VS Code-da F5, Alqor Studio-da 🐞 Debaq. Aşağıdakı terminal konsolu (alqor debaq) və kodda dayanNöqtəsi hələ planlaşdırılır ⏳.

alqor debaq əsas.alq

// Kodda breakpoint
dayanNöqtəsi

// Debaq çapı
çap(dəyişən)                 // strukturlu, tiplərlə
çap!(ifadə)                  // ifadəni və nəticəsini çap edir
                             // → "x + y = 15"

alqor-debaq> davam
alqor-debaq> addım            # bir sətir irəli
alqor-debaq> içəri            # funksiyaya gir
alqor-debaq> çıx              # funksiyadan çıx
alqor-debaq> dəyişənlər       # cari əhatədəki dəyişənlər
alqor-debaq> yığın            # çağırış yığını
alqor-debaq> çap x
alqor-debaq> qoy x = 5
alqor-debaq> dayanNöqtəsi əsas.alq:42
alqor-debaq> sil 1

13.11 Profil və performans#

alqor profil əsas.alq
alqor profil --yaddaş
alqor profil --alov-qrafiki     # flame graph

  Funksiya                    Çağırış    Ümumi      Öz
  ────────────────────────────────────────────────────────
  hesablaHamısı()                   1   1.243s    0.012s
    emal()                      10000   1.180s    0.890s
      çevir()                   10000   0.290s    0.290s
    yaz()                         100   0.051s    0.051s

13.12 CI/CD#

.github/workflows/alqor.yml:

name: Alqor CI
on: [push, pull_request]
jobs:
  yoxla:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: alqor-dili/quraşdır@v1
        with:
          versiya: '1.0.0'
      - run: alqorfmt --yoxla .
      - run: alqorlint .
      - run: alqor yoxla
      - run: alqortest --örtük
      - run: alqor qur --buraxılış
      - run: alqor paketlə --hədəf deb

13.13 Mühit dəyişənləri#

Etalon implementasiyada hazırda ALQOR_RENG, ALQOR_BASSIZ, NO_COLOR, PORT/ALQOR_PORT, ALQOR_HOST və ALQOR_KES oxunur; qalanları kompilyator və paket meneceri ilə gələcək.

Niyə adlar ASCII-dir? ALQOR_RƏNG kimi ad shell-də təyin oluna bilmir — POSIX mühit dəyişəni adları yalnız [A-Za-z_][A-Za-z0-9_]* ola bilər, Windows set əmri isə UTF-8 adları ümumiyyətlə qəbul etmir. Dəyişən adları ASCII-dir, dəyərləri isə Azərbaycan dilindədir (ALQOR_RENG=həmişə).

13.14 JavaScript hədəfi ✅#

Alqor proqramı Python olmadan — Node.js-də və ya brauzerdə — işləyə bilər. Kompilyator (alqor/js/derleyici.py) AAC-ni ES2020 JavaScript-ə çevirir, icra mühiti (alqor/js/icra.js) nəticəyə daxil edilir: tək fayl alınır.

alqor işlət --js proqram.alq           # çevirib node ilə dərhal işlədir
alqor qur --hədəf js  proqram.alq      # → qurma/proqram.js   (node proqram.js)
alqor qur --hədəf veb proqram.alq      # → qurma/veb/index.html
alqor qur --hədəf js --çıxış a.js      # layihə qovluğunda: giriş faylı

Semantika etalon icraçı ilə eynidir: sinaq/test_js.py test_icraci-dəki bütün kod parçalarını və sinaq/js_numuneler/ proqramlarını hər iki icrada işlədib çıxışı sətir-sətir müqayisə edir. Hesablama ağır proqramlarda JS hədəfi ~10 dəfə sürətlidir.

Dəstəklənən modullar: riyaziyyat, mətn, təsadüfi, vaxt, json, naxış, sistem, jurnal, paralel (ardıcıl), konsol (brauzerdə rəngsiz; arqumentlər yoxdur), fayl/qovluq/yol (yalnız node), vidjet, pəncərə (+ pəncərə.dialoq, pəncərə.sınaq), http, yerli fayllar (gətir "./x.alq") və paketlər/ paketləri — hamısı bir fayla yığılır. veb, sap və qalan alqor/modullar/ modulları kompilyasiya xətası verir (istisna: pəncərə idxal edən proqramda veb kompilyasiya olunur, çağırılanda icra xətası verir).

İnterfeys proqramları brauzerdə (serversiz)#

gətir pəncərə olan proqram qur --hədəf veb / yerləşdir ilə interfeys səhifəsinə çevrilir: menyu sətri, #alqor-kök, pəncərə və vidjet üslubu (pencere.ÜSLUB + vidjet.ÜSLUB) və Python pəncərəsinin brauzer nüvəsi (yamaq(), hadisə növbəsi). Model Python ilə eynidir — göstər() nəticəsi HTML-ə çevrilir, idarəedicilər data-a-klik="n1h3" reyestrinə yazılır — fərq yalnız göndərmədədir: hadisə HTTP sorğusu ilə serverə yox, birbaşa səhifədəki icra mühitinə gedir, sonra kök yenidən göstərilir və DOM yamanır (yazılan sahənin fokusu və dəyəri qalır).

İdarəedicidə xəta interfeysi silmir: səhifənin altında bağlana bilən xəta qutusu görünür. Node.js-də pəncərə açılmır (Python-un başsız rejimi kimi): pəncərə.sınaq sürücüsü və dialoq cavabları növbəsi işləyir, ona görə 06-desktop.alq -- sınaq hər iki icrada eyni nəticə verir.

Vidjetlər. vidjet.py və vidjet_elave.py funksiyaları əl ilə köçürülmür: vidjet_cevir.py Python AAC-sini (ast) JS-ə çevirir, Python əməliyyatları vidjet_komekci.js köməkçiləri ilə ifadə olunur (doğruluq, %, dilim, f"{x:g}"). Yeni vidjet əlavə edildikdə JS hədəfi avtomatik onu da alır; naməlum Python konstruksiyası çeviricidə xəta verir. sinaq/test_js.py hər vidjeti (standart və dolu arqumentlərlə) hər iki icrada qurub HTML-i müqayisə edir; Playwright sınaqları Chromium-da klik → DOM yenilənməsini yoxlayır.

http Node.js-də uşaq prosesdə fetch ilə sinxron icra olunur (gözlə http.al(...) Python-dakı kimi bloklayır). faylYüklə, faylGöndər, vebSoket JS hədəfində yoxdur.

Fərqlər: paralel əməliyyatları ardıcıl işləyir; vaxt.gözlə brauzerdə məşğul gözləmədir; JS stek həddi aşılarsa StekDaşmaXətası atılır.

13.15 Konsol kodlaşdırması (vacib)#

Alqor alətləri işə düşərkən standart çıxışı məcburi UTF-8-ə keçirir.

Səbəb: Windows-da Python/cmd.exe/PowerShell standart çıxış kodlaşdırması sistemin kod səhifəsidir (məs. cp1251, cp857). Belə olanda alət öz Azərbaycan dilindəki xəta mesajını çap edə bilmir və UnicodeEncodeError ilə dayanır.

ALQOR_KODLASMA=sistem ilə bu davranış söndürülə bilər (tövsiyə olunmur).

13.16 Çıxış kodları#